<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Permanent Message Handling</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Getting Started with Replicated Berkeley DB Applications" />
    <link rel="up" href="repapp.html" title="Chapter 3. The DB Replication Manager" />
    <link rel="prev" href="repmgr_init_example_c.html" title="Adding the Replication Manager to RepMgr" />
    <link rel="next" href="electiontimes.html" title="Managing Election Times" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Permanent Message Handling</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 3. The DB Replication Manager</th>
          <td width="20%" align="right"> <a accesskey="n" href="electiontimes.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="fwrkpermmessage"></a>Permanent Message Handling</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="fwrkpermmessage.html#fmwrkpermpolicy">Identifying Permanent Message Policies</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="fwrkpermmessage.html#fmwrkpermtimeout">Setting the Permanent Message Timeout</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="fwrkpermmessage.html#perm2fmwrkexample">Adding a Permanent Message Policy to 
                            
                            <span>RepMgrGSG</span>
                            
                    </a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
               As described in <a class="xref" href="permmessages.html" title="Permanent Message Handling">Permanent Message Handling</a>,
               messages are marked permanent if they contain database
               modifications that should be committed at the replica.
               DB's replication code decides if it must flush its
               transaction logs to disk depending on whether it receives
               sufficient permanent message acknowledgments from the
               participating replicas. More importantly, the thread 
               performing the transaction commit blocks
               until it either receives enough acknowledgments, or the
               acknowledgment timeout expires.
            </p>
      <p>
                The Replication Manager is fully capable of managing permanent messages
                for you if your application requires it (most do). 
                Almost all of the details of this are handled by the 
                Replication Manager for you. However, you do have to set some policies
                that tell the Replication Manager how to handle permanent messages.
            </p>
      <p>
                There are two things that you have to do:
            </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
                                    Determine how many acknowledgments
                                    must be received by the master.
                            </p>
          </li>
          <li>
            <p>
                                    Identify the amount of time that
                                    replicas have to send their
                                    acknowledgments.
                            </p>
          </li>
        </ul>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="fmwrkpermpolicy"></a>Identifying Permanent Message Policies</h3>
            </div>
          </div>
        </div>
        <p>

                        You identify permanent message policies using the
                        

                        

                        Note that you can set permanent message
                        policies at any time during the life of the
                        application.
                    </p>
        <p>
        The following permanent message policies are available when you use
        the Replication Manager:
</p>
        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <h3 class="title">Note</h3>
          <p>
        The following list mentions <span class="emphasis"><em>electable peer</em></span>
        several times. This is simply another environment that can be
        elected to be a master (that is, it has a priority greater than 0).
        Do not confuse this with the concept of a peer as used for client
        to client transfers. See <a class="xref" href="c2ctransfer.html" title="Client to Client Transfer">Client to Client Transfer</a> for more information on client
        to client transfers.
    </p>
        </div>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                        <code class="literal">DB_REPMGR_ACKS_NONE</code>
                        
                </p>
              <p>
                    No permanent message acknowledgments are required. If
                    this policy is selected, permanent message handling is
                    essentially "turned off." That is, the master will
                    never wait for replica acknowledgments. In this case,
                    transaction log data is either flushed or not strictly
                    depending on the type of commit that is being performed
                    (synchronous or asynchronous).
                </p>
            </li>
            <li>
              <p>
                        <code class="literal">DB_REPMGR_ACKS_ONE</code>
                        
                </p>
              <p>
                    At least one replica must acknowledge the permanent
                    message within the timeout period.  
                </p>
            </li>
            <li>
              <p>
                        <code class="literal">DB_REPMGR_ACKS_ONE_PEER</code>
                        
                </p>
              <p>
                    At least one electable peer must acknowledge the permanent
                    message within the timeout period. 
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">DB_REPMGR_ACKS_ALL</code>
                    
                </p>
              <p>
                    All replicas must acknowledge the message within
                    the timeout period. This
                    policy should be selected only if your replication
                    group has a small number of replicas, and those replicas
                    are on extremely reliable networks and servers.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">DB_REPMGR_ACKS_ALL_AVAILABLE</code>
                    
                </p>
              <p>
                    All currently connected replication clients must
                    acknowledge the message.  This policy will invoke the
                    <code class="literal">DB_EVENT_REP_PERM_FAILED</code> event if
                    fewer than a quorum of clients acknowledged during that
                    time. 
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">DB_REPMGR_ACKS_ALL_PEERS</code>
                    
                </p>
              <p>
                    All electable peers must acknowledge the message within the
                    timeout period. This
                    policy should be selected only if your replication
                    group is small, and its various environments
                    are on extremely reliable networks and servers.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">DB_REPMGR_ACKS_QUORUM</code>
                    
                </p>
              <p>
                    A quorum of electable peers must acknowledge the message within the timeout period. 
                    A quorum is reached when acknowledgments are received from the minimum number 
                    of environments needed to ensure that the record remains durable 
                    if an election is held. That is, the master wants to hear from enough 
                    electable replicas that they have committed the record so that if an election 
                    is held, the master knows the record will exist even if a new master is selected.
                </p>
            </li>
          </ul>
        </div>
        <p>
        By default, a quorum of electable peers must must acknowledge a permanent
        message in order for it considered to have been successfully
        transmitted. 
</p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="fmwrkpermtimeout"></a>Setting the Permanent Message Timeout</h3>
            </div>
          </div>
        </div>
        <p>
                            The permanent message timeout represents the
                            maximum amount of time the committing thread
                            will block waiting for message
                            acknowledgments. If sufficient
                            acknowledgments arrive before this timeout has
                            expired, the thread continues operations as
                            normal. However, if this timeout expires, the
                            committing thread flushes its transaction log
                            buffer before continuing with normal
                            operations.
                    </p>
        <p>
                        You set the timeout value using the
                        
                        <code class="methodname">DbEnv::rep_set_timeout()</code>
                        method. When you do this, you provide the 
                        <code class="literal">DB_REP_ACK_TIMEOUT</code> value to
                        the <code class="literal">which</code> parameter, and the
                        timeout value in microseconds to the
                        <code class="literal">timeout</code> parameter.
                    </p>
        <p>
                        For example:
                    </p>
        <pre class="programlisting">    dbenv-&gt;rep_set_timeout(DB_REP_ACK_TIMEOUT, 100); </pre>
        <p>
                        This timeout value can be set at anytime during the
                        life of the application. 
                    </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="perm2fmwrkexample"></a>Adding a Permanent Message Policy to 
                            
                            <span>RepMgrGSG</span>
                            
                    </h3>
            </div>
          </div>
        </div>
        <p>
                        For illustration purposes, we will now update 
                        
                        <code class="literal">RepMgrGSG</code>
                        
                        such that it requires only one acknowledgment from
                        a replica on transactional commits. Also, we will give
                        this acknowledgment a 500 microsecond timeout
                        value. This means that our application's main
                        thread will block for up to 500 microseconds waiting
                        for an acknowledgment. If it does not receive at
                        least one acknowledgment in that amount of time,
                        DB will flush the transaction logs to disk
                        before continuing on.
                    </p>
        <p>
                        This is a very simple update. We can perform the
                        entire thing in 
                        <code class="methodname">RepMgrGSG::init()</code>
                        
                        immediately after we set the application's priority
                        and before we open our environment handle.
                    </p>
        <pre class="programlisting">int RepMgrGSG::init(RepConfigInfo *config)
{
    int ret = 0;

    app_config = config;

    dbenv.set_errfile(stderr);
    dbenv.set_errpfx(progname);

    DbSite *dbsite;
    dbenv.repmgr_site(app_config-&gt;this_host.host,
        app_config-&gt;this_host.port, &amp;dbsite, 0);
    dbsite-&gt;set_config(DB_LOCAL_SITE, 1);
    if (app_config-&gt;this_host.creator)
        dbsite-&gt;set_config(DB_GROUP_CREATOR, 1);

    dbsite-&gt;close();

    int i = 1;
    for ( REP_HOST_INFO *cur = app_config-&gt;other_hosts; 
        cur != NULL &amp;&amp; i &lt;= app_config-&gt;nrsites;
        cur = cur-&gt;next, i++) {
            dbenv.repmgr_site(cur-&gt;host, cur-&gt;port, &amp;dbsite, 0);
            dbsite-&gt;set_config(DB_BOOTSTRAP_HELPER, 1);

            dbsite-&gt;close();
    }

    dbenv.rep_set_priority(app_config-&gt;priority);

    <strong class="userinput"><code>/* Permanent messages require at least one ack */
    dbenv.repmgr_set_ack_policy(DB_REPMGR_ACKS_ONE);
    /* Give 500 microseconds to receive the ack */
    dbenv.rep_set_timeout(DB_REP_ACK_TIMEOUT, 500);</code></strong>

    dbenv.set_cachesize(0, CACHESIZE, 0);
    dbenv.set_flags(DB_TXN_NOSYNC, 1);

    ... </pre>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="repapp.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="electiontimes.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Adding the Replication Manager to
                
                <span>RepMgr</span>
                
         </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Managing Election Times</td>
        </tr>
      </table>
    </div>
  </body>
</html>
